home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / basic / pbasmlib.zip / ARRAY.DOC < prev    next >
Text File  |  1994-02-12  |  13KB  |  269 lines
  1. PBASMLIB Assembly Language Routines for PB3C
  2. Version 1.0
  3. Integer/Word Array Manipulation Routines (ARRAY)
  4. (C) Copyright 1994 by Tim Gerchmez
  5. All Rights Reserved.
  6.  
  7. This unit contains many routines that manipulate numeric (integer and
  8. word) arrays in various ways, all of them lightning-quick in assembly
  9. language.  It is contained in PBASMLIB.PBL, and the routines listed here
  10. will be immediately accessible using $INCLUDE "PBASMLIB.INC" and
  11. $LINK "PBASMLIB.PBL" at the top of your programs.
  12.  
  13. CAUTION: These routines do not do error checking.  Be sure to pass
  14.      them only valid values, or sections of memory may be unintentionally
  15.      overwritten.  For example, calling FILLARRAY with a 5-element integer
  16.      array, and asking it to fill 10 elements starting with the first, will
  17.      cause problems, and may result in a system crash.
  18.  
  19. The ARRAY module supports both integer and word arrays.  Integer arrays
  20. elements have a value from -32768 to +32767 (I.E. they are signed), while
  21. word array elements have a value ranging from 0 to 65535 (unsigned).  Only
  22. single-dimensional arrays are supported by this module, and an array can be
  23. dimensioned to only integer values (I.E. the maximum LBOUND is -32768 and the
  24. maximum UBOUND is 32767).  This allows you to use arrays that are up to 64K
  25. elements in length.  For example, the following BASIC code is valid:
  26.  
  27. dim ary%(-32768 to 32767)
  28. call fillarray(ary%(-32768,65535,10) 'Fills elements -32768 to 32767 with 10
  29.  
  30. The formula for calculating the highest element filled given the parameters most
  31. of these commands use is (start element + number of elements) - 1.  For example,
  32. if you use [FILLARRAY AR%(-11),80,10], calculate the top element by using
  33. (-11 + 80) - 1, which means that element 68 will be the highest element filled.
  34.  
  35. Note: a "bug" in PowerBASIC prevents you from accessing the entire contents of
  36. an array using a for/next loop with an integer counter variable.  For example,
  37. the following code will cause an OVERFLOW error:
  38.  
  39. dim ary%(-32768 to 32767)
  40. for t% = -32768 to 32767 : print ary%(t%) : next t%
  41.  
  42. This is because the last iteration of the loop will increase the loop variable
  43. one number beyond the upper limit, causing an error condition.  For this reason,
  44. it's recommended that you use 32766 for a UBOUND limit with arrays rather than
  45. the value 32767.
  46.  
  47. ================================================================================
  48. sub negarray(ary%(se%),ne??)
  49.  
  50. Negates the values of an integer array, making negative
  51. numbers positive and positive numbers negative.  Starts with
  52. a particular element and continues for a particular number of
  53. elements.  This command applies to integer arrays only, as negation
  54. is a moot point with word arrays.
  55.  
  56. ary%(se%): Set se% to the starting element you want to negate in ary%.
  57.           Only integer arrays can be passed to this routine.
  58. ne??:      Set to the number of elements to negate, starting with and
  59.           including the number specified with se%.
  60.  
  61. Example: negarray ary%(1),50   'Negate elements 1 through 50
  62. Example: negarray ary%(-80),41 'Negate elements -80 through -40
  63.  
  64. ================================================================================
  65. sub shrarray(ary(se%),ne??,ct%)
  66.  
  67. Shifts the bits of each element in an integer or
  68. word array right (SHR) by a certain number of bits.
  69. This effectively divides each number by 2 times
  70. the number of bits shifted [ary%(se%)\(ct% * 2)].
  71.  
  72. ary(se%): Set se% to the start element of the array to SHR.  Either
  73.          integer or word arrays can be passed.
  74. ne??:     Set to number of elements to SHR, inclusive of the
  75.          first element specified in se%.
  76. ct%:      Set to number of bits to shift right by
  77.  
  78. Example:  shrarray ary%(1),100,1  'Shifts elements 1 through 100 right by one bit
  79. Example:  shrarray ary%(-5),11,4  'Shifts elements -5 through 5 right by 4 bits
  80. Example:  shrarray ary??(1),100,2 'Shifts elements 1 through 100 right by 2 bits
  81.  
  82. ================================================================================
  83. sub shlarray(ary(se%),ne??,ct%)
  84.  
  85. Shifts the bits of each element in an integer or
  86. word array left (SHL) by a certain number of bits.
  87. This effectively multiplies each number by 2 times
  88. the number of bits shifted [ary%(se%)*(ct% * 2)].
  89.  
  90. ary(se%): Set se% to the start element of the array to SHL.  Either
  91.          integer or word arrays can be passed.
  92. ne??:     Set to number of elements to SHL, inclusive of the
  93.          first element specified in se%.
  94. ct%:      Set to number of bits to shift left by
  95.  
  96. Example:  shlarray ary%(1),100,1  'Shifts elements 1 through 100 left by one bit
  97. Example:  shlarray ary%(-5),11,4  'Shifts elements -5 through 5 left by 4 bits
  98. Example:  shlarray ary??(1),100,2 'Shifts elements 1 through 100 left by 2 bits
  99.  
  100. ================================================================================
  101. sub rorarray(ary(se%),ne??,ct%)
  102.  
  103. Rotates the bits of each element in an integer or
  104. word array right (ROR) by a certain number of bits.
  105.  
  106. ary(se%): Set se% to the start element of the array to ROR.  Either
  107.          integer or word arrays can be passed.
  108. ne??:     Set to number of elements to ROR, inclusive of the
  109.          first element specified in se%.
  110. ct%:      Set to number of bits to rotate right by
  111.  
  112. Example:  rorarray ary%(1),100,1  'Rotates elements 1 through 100 right by one bit
  113. Example:  rorarray ary%(-5),11,4  'Rotates elements -5 through 5 right by 4 bits
  114. Example:  rorarray ary??(1),100,2 'Rotates elements 1 through 100 right by 2 bits
  115.  
  116. ================================================================================
  117. sub rolarray(ary(se%),ne??,ct%)
  118.  
  119. Rotates the bits of each element in an integer or
  120. word array left (ROL) by a certain number of bits.
  121.  
  122. ary(se%): Set se% to the start element of the array to ROL.  Either
  123.          integer or word arrays can be passed.
  124. ne??:     Set to number of elements to ROL, inclusive of the
  125.          first element specified in se%.
  126. ct%:      Set to number of bits to rotate left by
  127.  
  128. Example:  rolarray ary%(1),100,1  'Rotates elements 1 through 100 left by one bit
  129. Example:  rolarray ary%(-5),11,4  'Rotates elements -5 through 5 left by 4 bits
  130. Example:  rolarray ary??(1),100,2 'Rotates elements 1 through 100 left by 2 bits
  131.  
  132. ================================================================================
  133. sub notarray(ary(se%),ne??)
  134.  
  135. Logically NOTs the bits of each element in an integer or word array
  136. with a given value, starting with a particular element and continuing
  137. for a particular number of elements.  This forms the one's complement
  138. (inverts the bits) of the array elements.
  139.  
  140. ary(se%): Set se% to the start element of the array to NOT.  Either
  141.          integer or word arrays can be passed.
  142. ne??:     Set to number of elements to NOT, inclusive of the
  143.          first element specified in se%.
  144.  
  145. Example:  notarray ary%(1),100    'NOTs elements 1 through 100
  146. Example:  notarray ary%(-5),11    'NOT elements -5 through 5
  147. Example:  notarray ary??(1),100   'NOT elements 1 through 100
  148.  
  149. ================================================================================
  150. sub xorarray(ary(se%),ne??,xv??)
  151.  
  152. Exclusive-OR's (XOR's) the values of each element in an integer or
  153. word array with a given value, starting with a particular element
  154. and continuing for a particular number of elements.
  155.  
  156. ary(se%): Set se% to the start element of the array to XOR.  Either
  157.          integer or word arrays can be passed.
  158. ne??:     Set to number of elements to XOR, inclusive of the
  159.          first element specified in se%.
  160. av??:     Set to the word value (0-65535) to XOR each array element
  161.          with (see examples below).
  162.  
  163. Example:  xorarray ary%(1),100,32     'XORs elements 1 through 100 with 32,
  164.                                   'toggling bit 5.
  165. Example:  xorarray ary%(-5),11,40     'XOR elements -5 through 5 with 40,
  166.                                   'toggling bits 5 and 3.
  167. Example:  xorarray ary??(1),100,65535 'XOR elements 1 through 100 with 65535,
  168.                                   'toggling all bits.
  169.  
  170. ================================================================================
  171. sub orarray(ary(se%),ne??,ov??)
  172.  
  173. Logically ORs the values of each element in an integer or word
  174. array with a given value, starting with a particular element and
  175. continuing for a particular number of elements.
  176.  
  177. ary(se%): Set se% to the start element of the array to OR.  Either
  178.           integer or word arrays can be passed.
  179. ne??:     Set to number of elements to OR, inclusive of the
  180.          first element specified in se%.
  181. av??:     Set to the word value (0-65535) to OR each array element
  182.          with (see examples below).
  183.  
  184. Example:  orarray ary%(1),100,32    'ORs elements 1 through 100 with 32,
  185.                                 'switching on bit 5 if not already set.
  186. Example:  orarray ary%(-5),11,40    'OR elements -5 through 5 with 40,
  187.                                 'switching on bits 5 and 3.
  188. Example:  orarray ary??(1),100,8192 'OR elements 1 through 100 with 8192.
  189.  
  190. ================================================================================
  191. sub andarray(ary(se%),ne??,av??)
  192.  
  193. Logically ANDs the values of each element in an integer or word
  194. array with a given value, starting with a particular element and
  195. continuing for a particular number of elements.
  196.  
  197. ary(se%): Set se% to the start element of the array to AND.  Either
  198.           integer or word arrays can be passed.
  199. ne??:     Set to number of elements to AND, inclusive of the
  200.          first element specified in se%.
  201. av??:     Set to the word value (0-65535) to AND each array element
  202.          with (see examples below).
  203.  
  204. Example:  andarray ary%(1),100,31    'AND elements 1 through 100 with 31,
  205.                                  'limiting to values between 0 and 31.
  206. Example:  andarray ary%(-5),11,40    'AND elements -5 through 5 with 40.
  207. Example:  andarray ary??(1),100,8192 'AND elements 1 through 100 with 8192.
  208.  
  209. ================================================================================
  210. sub addarray(ary(se%),ne??,va%)
  211.  
  212. Adds a given value to each element of an integer or word array,
  213. starting with a particular element and continuing for a particular
  214. number of elements.
  215.  
  216. ary(se%): Set se% to the start element of the array to add the
  217.          value to.  Either integer or word arrays can be passed.
  218. ne??:     Set to number of elements to add the value to, inclusive
  219.          of the first element specified in se%.
  220. va%:      Set to the integer value to add to the specified array elements.
  221.          To subtract, add a negative value.  If the calculated new value
  222.          exceeds the limits of an integer/word value, it will "wrap around"
  223.          rather than causing an error.  To add a word-length value to a word
  224.          array, use the BITS% statement (see last example below).
  225.  
  226. Example: addarray ary%(1),100,32 'Add 32 to elements 1 through 100 of ary%().
  227. Example: addarray ary%(-5),11,40 'Adds 40 to elements -5 through 5 of ary%().
  228. Example: addarray ary??(1),100,-32 'Subtract 32 from elements 1 through 100 of ary??().
  229. Example: addarray ary??(1),10,bits%(40000) 'Add 40000 to elements 1 through 10 of ary??().
  230.  
  231. ================================================================================
  232. sub randfillarray(ary(se%),ne??)
  233.  
  234. Fills (initializes) an integer or word array with
  235. pseudo-random values (-32768 to 32767 for INT arrays
  236. or 0 to 65535 for word arrays.)  Use ANDARRAY to limit
  237. the array to certain ranges of values.
  238.  
  239. ary(se%): Set to array to fill, with se% equalling the starting
  240.          (first) element to fill.  Integer or word arrays can
  241.          be passed.
  242. ne??:     Set to number of elements to fill, including the first
  243.          element (se%).  See example below.
  244.  
  245. Example: randfillarray ary%(1),100  'Fills elements 1 through 100 with random values
  246. Example: randfillarray ary%(-10),20 'Fills elements -10 through 9 with random values
  247. Example: randfillarray ary??(5),10  'Fills elements 5 through 15 with random values
  248.  
  249. ================================================================================
  250. sub fillarray(ary(se%),ne??,v%)
  251.  
  252. Fills (initializes) an integer or word array with a
  253. certain specific value.
  254.  
  255. ary(se%): Set to array to fill, with se% equalling the starting
  256.          (first) element to fill.  Integer or word arrays can
  257.          be passed.
  258. ne??:     Set to number of elements to fill, including the first
  259.          element (se%).  See example below.
  260. v%:       Set to value to fill array with (integer only).  To
  261.          convert a word value, use the BITS% command.
  262.  
  263. Example: fillarray ary%(1),100,-10 'Fills elements 1 through 100 with -10.
  264. Example: fillarray ary%(-10),20,50 'Fills elements -10 through 9 with 50.
  265. Example: fillarray ary??(5),10,32  'Fills elements 5 through 15 with 32.
  266. Example: fillarray ary??(1),100,bits%(65000) 'Fills elements 1 through 100
  267.                                         'with the value 65000.
  268.  
  269.